---
title: "Link"
description: "Links allow users to click their way from page to page. This component is styled to resemble a hyperlink and semantically renders an <a>"
---

import {linkContent} from "@/content/components/link";

# Link

Links allow users to click their way from page to page. This component is styled to resemble a hyperlink and semantically renders an `<a>`

<ComponentLinks component="link" reactAriaHook="useLink" />

---

<CarbonAd/>

## Installation

<PackageManagers
  showGlobalInstallWarning
  commands={{
    cli: "npx heroui-cli@latest add link",
    npm: "npm install @heroui/link",
    yarn: "yarn add @heroui/link",
    pnpm: "pnpm add @heroui/link",
    bun: "bun add @heroui/link"
  }}
/>

## Import

<ImportTabs
  commands={{
    main: 'import {Link} from "@heroui/react";',
    individual: 'import {Link} from "@heroui/link";',
  }}
/>

## Usage

<CodeDemo title="Usage" files={linkContent.usage} />

### Disabled

<CodeDemo title="Disabled" files={linkContent.disabled} />

### Sizes

<CodeDemo title="Sizes" files={linkContent.sizes} />

### Colors

<CodeDemo title="Colors" files={linkContent.colors} />

### Underline

<CodeDemo title="Underline" files={linkContent.underline} />

### External

If you pass the `isExternal` prop, the link will have the `target="_blank"` and `rel="noopener noreferrer"` attributes.

<CodeDemo title="External" files={linkContent.external} />

### Custom Anchor Icon

<CodeDemo title="Custom Anchor Icon" files={linkContent.customAnchorIcon} />

### Block Link

If you pass the `isBlock` prop, the link will be rendered as a block element with a `hover` effect.

<CodeDemo title="Block Link" files={linkContent.block} />

### Polymorphic Component

HeroUI's components expose a `as` prop that allows you to customize the React element type that is used to render the component.

<CodeDemo title="Polymorphic Component" files={linkContent.polymorphic} />

### Routing

The `<Link>` component works with frameworks and client side routers like [Next.js](https://nextjs.org/) and 
[React Router](https://reactrouter.com/en/main). See the [Routing](/docs/guide/routing) guide to learn how to set this up.


```jsx
import {Link} from "@heroui/react";

function App() {
  return (
    <>
      <Link href="/home">Home</Link>
      <Link href="/about">About</Link>
    </>
  );
}
```

### Custom Implementation

In case you need to customize the link even further, you can use the `useLink` hook to create your own implementation.

<CodeDemo showPreview={false} showOpenInCodeSandbox={false} title="Custom implementation" files={linkContent.customImpl} />

<Spacer y={4} />

## Data Attributes

`Link` has the following attributes on the `base` element:

- **data-focus**:
  When the link is being focused. Based on [useFocusRing](https://react-spectrum.adobe.com/react-aria/useFocusRing.html)
- **data-focus-visible**:
  When the link is being focused with the keyboard. Based on [useFocusRing](https://react-spectrum.adobe.com/react-aria/useFocusRing.html)
- **data-disabled**:
  When the link is disabled. Based on `isDisabled` prop.

<Spacer y={4} />

## Accessibility

- Support for mouse, touch, and keyboard interactions.
- Support for navigation links via `<a>` elements or custom element types via ARIA.
- Support for disabled links.
- Keyboard users may activate links using the <Kbd>Enter</Kbd> key.

<Spacer y={4} />

## API

### Link Props

<APITable
  data={[
    {
      attribute: "size",
      type: "sm | md | lg",
      description: "The size of the link.",
      default: "md"
    },
    {
      attribute: "color",
      type: "foreground | primary | secondary | success | warning | danger",
      description: "The color of the link.",
      default: "primary"
    },
    {
      attribute: "underline",
      type: "none | hover | always | active | focus",
      description: "The underline style of the link.",
      default: "none"
    },
    {
      attribute: "href",
      type: "string",
      description: "A URL to link to. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#href).",
      default: "-"
    },
    {
      attribute: "target",
      type: "HTMLAttributeAnchorTarget",
      description: "The target window for the link. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#target).",
      default: "-"
    },
    {
      attribute: "rel",
      type: "string",
      description: "The relationship between the linked resource and the current page. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel).",
      default: "-"
    },
    {
      attribute: "download",
      type: "boolean | string",
      description: "Causes the browser to download the linked URL. A string may be provided to suggest a file name. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#download).",
      default: "-"
    },
    {
      attribute: "ping",
      type: "string",
      description: "A space-separated list of URLs to ping when the link is followed. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#ping).",
      default: "-"
    },
    {
      attribute: "referrerPolicy",
      type: "HTMLAttributeReferrerPolicy",
      description: "How much of the referrer to send when following the link. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#referrerpolicy).",
      default: "-"
    },
    {
      attribute: "isExternal",
      type: "boolean",
      description: "Whether the link should open in a new tab.",
      default: "false"
    },
    {
      attribute: "showAnchorIcon",
      type: "boolean",
      description: "Whether to show the anchor icon.",
      default: "false"
    },
    {
      attribute: "anchorIcon",
      type: "ReactNode",
      description: "The anchor icon.",
      default: "-"
    },
    {
      attribute: "isBlock",
      type: "boolean",
      description: "Whether the link should be rendered as block with a hover effect.",
      default: "false"
    },
    {
      attribute: "isDisabled",
      type: "boolean",
      description: "Whether the link is disabled.",
      default: "false"
    },
    {
      attribute: "disableAnimation",
      type: "boolean",
      description: "Whether to disable link and block animations.",
      default: "false"
    }
  ]}
/>

### Link Events

<APITable
  data={[
    {
      attribute: "onPress",
      type: "(e: PressEvent) => void",
      description: "Handler called when the press is released over the target.",
      default: "-"
    },
    {
      attribute: "onPressStart",
      type: "(e: PressEvent) => void",
      description: "Handler called when a press interaction starts.",
      default: "-"
    },
    {
      attribute: "onPressEnd",
      type: "(e: PressEvent) => void",
      description: "Handler called when a press interaction ends, either over the target or when the pointer leaves the target.",
      default: "-"
    },
    {
      attribute: "onPressChange",
      type: "(isPressed: boolean) => void",
      description: "Handler called when the press state changes.",
      default: "-"
    },
    {
      attribute: "onPressUp",
      type: "(e: PressEvent) => void",
      description: "Handler called when a press is released over the target, regardless of whether it started on the target or not.",
      default: "-"
    },
    {
      attribute: "onKeyDown",
      type: "(e: KeyboardEvent) => void",
      description: "Handler called when a key is pressed.",
      default: "-"
    },
    {
      attribute: "onKeyUp",
      type: "(e: KeyboardEvent) => void",
      description: "Handler called when a key is released.",
      default: "-"
    },
    {
      attribute: "onClick",
      deprecated: true,
      type: "MouseEventHandler",
      description: "The native link click event handler (Deprecated) use onPress instead.",
      default: "-"
    }
  ]}
/>
